ReadMe for The RAT Extras
The Aztec33 Aztec C65 Apple II DOS 3.3 Compiler Distibution  

Pre-Release for Aztec33 - August, 2013
======================================

As of August 2013, the Aztec33 distribution is not quite ready to be
released, but several programs that have been written as example programs
for Aztec33 are being distributed as pre-release bundles.

Aztec33 is an Aztec C compiler bundle that contains 2 Aztec C compiler
releases of the same vintage (Circa 1983) for building programs that run in
DOS 3.3 on the Apple II:

1. A native mode compiler that runs on the Apple II under DOS 3.3.
2. An MS-DOS cross-compiler that creates Apple II DOS 3.3 programs.

To my knowledge, these compilers are the oldest Aztec C Apple II compilers
that are still in general existence.

When Aztec33 is released it will provide a complete compiler environment for
building Aztec C building DOS 3.3 programs for either the Aztec C DOS 3.3
Shell or for native mode DOS 3.3 using your choice of 2 working
environments:

1. Apple II DOS 3.3 (or Emulator)
2. MS-DOS (Windows Xp, Emulator)

Note: This early version ofAztec C65 (the 2 flavours of compiler that come
with Aztec33) are the only compilers that make these tiny DOS 3.3 Shell
Programs.

About the Programs in this Pre-Release Bundle
=============================================

The programs in this bundle all come on DOS 3.3 disk images and are complete
with source code. All  are targetted at the Aztec C Shell for DOS 3.3. This
is a "Unix-Like" Shell which provides a command line environment and very
tiny compiled C programs that work only in the shell. See some of the other
documents in this pre-release bundle for more information, and run the
program disks and read the source code that comes with all of this.

HOLA33.DSK 

hola - HGR Command Line Picture Viewer 

Command Line: hola HGRimage or hola -seconds HGRimage
Multiple images: can be entered for slideshow.
Slideshow Timeout: in seconds (default = 5)
hola commandline usage: hola -seconds HGRimagename
hola interactive usage: hola

LOLA33.DSK

lola (Lauging Out Loud Again) - LOGR Command Line Picture Viewer

Command Line: lola LOGRimage or lola -seconds LOGRimage 
Multiple images: can be entered for slideshow.
Slideshow Timeout: in seconds (default = 5)
hola commandline usage: hola -seconds HGRimagename
hola interactive usage: hola

SHROD33.DSK

ROD - LOGR "Kaleidescope" Graphics Demo

Loosely based on Rod's Color Pattern in C by Dr. John B. Matthews.
Which in turn is based on Rod's Color Pattern, written in Basic by Randy
Wigginton, which originally appeared on page 55 of the Red Book distributed
by Apple Computer, Inc. circa 1978. It was described as "a simple but
eloquent program. It generates a continuous flow of colored mosaic-like
patterns in a 40 high by 40 wide block matrix. Many of the patterns
generated by this program are pleasing to the eye and will dazzle the mind
for minutes at a time."

SHUTL33.DSK - Filters and Utility Programs.

CLS - clears the screen
CPCON - copies the console
DLIST - Creates Directory Lists using the DOS 3.3 catalog command  
ECHO - echo command for shell scripts
LCASE - lower case filter
LOTXT - sequential text file converter
MORE - text file filter
PAUSE - pause command for shell scripts
UCASE - upper case filter

Note: The C Programming Language (1st Edition) 
==============================================

The version of C described in The C Programming Language (1st Edition)
published in 1978 is referred to as K&R C, to distinguish it from ANSI C. In
1988 ANSI C was first standardized and The C Programming Language (2nd
Edition) was published to cover ANSI C.

Aztec CII Version 1.05i 6502 (this compiler) was released in 1983 (the same
year that ProDOS 8 was first released). It is exclusively for DOS 3.3 and
uses K&R C. By the time ANSI C came along, the Aztec CII compiler for the
Apple II had been replaced by Aztec C65 Version 3.2b (June 1987) which
offered support for both DOS 3.3 and ProDOS (which had taken over from DOS
3.3 by that time). The newer Version 3.2b also provided support for creating
programs for the newer Aztec C ProDOS Shell (which makes no sense at all),
but dropped support for the DOS 3.3 Aztec C Shell (this shell).

Aztec C65 Version 3.2b provided many ANSI C features but was still a K&R C
compiler. Version 3.2b was the last Aztec C compiler released for the Apple
II. It had already been released for a year (June 1987) by the time ANSI C
first came along and The C Programming Language (2nd Edition) was published.
An Aztec C65 ANSI C compiler for the Apple II was never released.

The Origin of Aztec33
=====================

A Hybrid Environment 
====================

This compiler environment contains 2-compilers:

1. Apple II DOS 3.3 Native Mode Compiler

This compiler is the same compiler described in the Manx Aztec C Mini-manual
(January 13,2001) by Rubywand (Jeff Hurlburt) of the comp.sys.apple2 usenet
newsgroup.

The native mode compiler works just fine for building both DOS 3.3 shell
programs which can't be built with the newer compiler, and "RAW" DOS 3.3
Stand-alone programs. And unlike the newer 3.2b Aztec C MS-DOS cross-
compiler and native mode compilers which both have difficulty on exit from
DOS 3.3 programs, this earlier native-mode compiler builds DOS 3.3
applications that exit cleanly. Exiting cleanly from an Aztec C program can
be important since files need to closed, etc.

The native mode compiler can work pretty quickly, in emulators like AppleWin
which provide a fast-speed option. Disk Image utilities like CiderPress make
it easy to move files back and forth between Windows and a DOS 3.3 disk
image, so it is not a great hardship to use the native mode compiler, but
the cross-compiler is a little more convenient.

2. MS-DOS cross-compiler for Apple II DOS 3.3 (originally for Commodore 64)

This version of the MS-DOS cross-compiler has been a work in progress for
several years. I originally purchased the compiler to create Commodore 64
programs around 1990. But I did not use the compiler. It sat for about 18
years and 2 of the original disks became damaged (one was entirely
unusable). I managed to resurrect the compiler in 2007 to create native mode
Commodore 64 programs under Windows XP or MS-DOS.

In 2009 I discovered that I could use the SHELL compiler for the Commodore
64 to create programs for the Apple II DOS 3.3 Shell by using a link library
from the Apple II's native mode compiler of the same vintage.

Operating System Notes - cross-compiling in MS-DOS or an Emulator
=================================================================

Both the Windows XP Command Line and MS-DOS Command Line work with the
cross-compiler. The MS-DOS cross-compiler also likely works on most Unix-
like systems, in an emulator like DOSEMU or DOSBox.

This is a very old cross-compiler. In Windows Vista, the DOSBox Emulator
worked with this. By the time Windows 7 came, even DOSBox no longer worked
with this. This will work under Windows 7 using VirtualBOX and FreeDOS, but
this a complicated set-up with a fragmented installer for drive-sharing that
I have not been able to intall properly, so I am working on other solutions.
I am not sure about Windows 8.

The Apple II native-mode compiler bundled with Aztec33 (this distribution)
works just fine and can be used in an Apple II emulator like AppleWIN, so
the native-mode compiler works everywhere that DOS 3.3 works.

Stand Alone Cross-Compiler C65.EXE Errata
=========================================

There is only one piece in this distribution that does not work properly.
All the other pieces work.

C65.EXE - The cross-compiler C65.EXE is exclusively for the Commodore 64. It
produces code for the Commodore 64 that is incompatible with the Apple II's
use of ZERO page memory. The Commodore 64's ZERO page is organized from $02
and the Apple II is organized from $00. 

I will probably write an assembly language pre-processor to correct this
problem, but in the meantime, DOS 3.3 Stand-Alone (SA) native mode programs
can't be built with this cross-compiler without using the native mode
compiler for the first-pass of the build.

This works:

1. Programs can be compiled to Assembly on the Apple II.
2. Assembly can then be moved to MS-DOS to produce REL (object files)
3. REL (object) files can then be linked with libraries in MS-DOS.

This seems to but doesn't:

1. Programs can be cross-compiled to Assembly in MS-DOS. The MS-DOS compiler
   adds an extra 2 bytes to the stack offset. Woops!
2. The cross-assembler creates a REL (object file).
3. The MS-DOS linker seems to work fine.
4. The programs crash or mis-behave or both.

And that concludes my notes for now. Enjoy the extras. There will be more to
come soon.

Bill Buckels
August 2013